fix(form-core): Prevent synchronous validators from returning Promises by mhuggins · Pull Request #1987 · TanStack/form

mhuggins · 2026-01-09T15:41:15Z

🎯 Changes

Passing an asynchronous function to a synchronous validator (i.e.: onBlur, onChange, onDynamic, onSubmit) is a bit of a foot-gun given that it does not produce any typescript errors, but it also results in the form/field validation function running after the core validation logic.

This updates the types for these validator functions on both FormApi and FieldApi to prevent passing a function that returns a Promise.

✅ Checklist

I have followed the steps in the Contributing guide.
I have tested this code locally with pnpm test:pr.

🚀 Release Impact

This change affects published code, and I have generated a changeset.

Summary by CodeRabbit

Bug Fixes
- Synchronous validators now enforce stricter type-checking to prevent returning Promises, catching incorrect usage patterns at compile-time and improving developer experience.

changeset-bot · 2026-01-09T15:41:20Z

🦋 Changeset detected

Latest commit: 6b927d2

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 13 packages

Name	Type
@tanstack/form-core	Patch
@tanstack/angular-form	Patch
@tanstack/form-devtools	Patch
@tanstack/lit-form	Patch
@tanstack/react-form	Patch
@tanstack/solid-form	Patch
@tanstack/svelte-form	Patch
@tanstack/vue-form	Patch
@tanstack/react-form-devtools	Patch
@tanstack/solid-form-devtools	Patch
@tanstack/react-form-nextjs	Patch
@tanstack/react-form-remix	Patch
@tanstack/react-form-start	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

Passing an asynchronous function to a synchronous validator (i.e.: `onBlur`, `onChange`, `onDynamic`, `onSubmit`) is a bit of a foot-gun given that it does not produce any typescript errors, but it also results in the form/field validation function running after the core validation logic. To prevent this, update the types for these validator functions on both `FormApi` and `FieldApi` to prevent passing a function that returns a `Promise`.

nx-cloud · 2026-01-10T09:48:28Z

View your CI Pipeline Execution ↗ for commit ec84898

Command	Status	Duration	Result
`nx affected --targets=test:sherif,test:knip,tes...`	✅ Succeeded	1m 10s	View ↗
`nx run-many --target=build --exclude=examples/**`	✅ Succeeded	25s	View ↗

☁️ Nx Cloud last updated this comment at 2026-05-10 19:36:22 UTC

pkg-pr-new · 2026-01-10T09:49:35Z

More templates

@tanstack/angular-form

npm i https://pkg.pr.new/@tanstack/angular-form@1987

@tanstack/form-core

npm i https://pkg.pr.new/@tanstack/form-core@1987

@tanstack/form-devtools

npm i https://pkg.pr.new/@tanstack/form-devtools@1987

@tanstack/lit-form

npm i https://pkg.pr.new/@tanstack/lit-form@1987

@tanstack/preact-form

npm i https://pkg.pr.new/@tanstack/preact-form@1987

@tanstack/react-form

npm i https://pkg.pr.new/@tanstack/react-form@1987

@tanstack/react-form-devtools

npm i https://pkg.pr.new/@tanstack/react-form-devtools@1987

@tanstack/react-form-nextjs

npm i https://pkg.pr.new/@tanstack/react-form-nextjs@1987

@tanstack/react-form-remix

npm i https://pkg.pr.new/@tanstack/react-form-remix@1987

@tanstack/react-form-start

npm i https://pkg.pr.new/@tanstack/react-form-start@1987

@tanstack/solid-form

npm i https://pkg.pr.new/@tanstack/solid-form@1987

@tanstack/solid-form-devtools

npm i https://pkg.pr.new/@tanstack/solid-form-devtools@1987

@tanstack/svelte-form

npm i https://pkg.pr.new/@tanstack/svelte-form@1987

@tanstack/vue-form

npm i https://pkg.pr.new/@tanstack/vue-form@1987

commit: ec84898

mhuggins · 2026-01-10T13:53:56Z

Just pushed an update that should address the lint issue, sorry about that!

codecov · 2026-01-10T17:34:55Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 90.76%. Comparing base (6892ed0) to head (ec84898).
⚠️ Report is 198 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #1987      +/-   ##
==========================================
+ Coverage   90.35%   90.76%   +0.41%     
==========================================
  Files          38       59      +21     
  Lines        1752     2209     +457     
  Branches      444      555     +111     
==========================================
+ Hits         1583     2005     +422     
- Misses        149      183      +34     
- Partials       20       21       +1

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

mhuggins · 2026-01-15T22:13:42Z

Just wanted to follow up to see if there's anything that's needed for this to be considered for acceptance. Thanks! 😄

LeCarbonator · 2026-01-16T06:44:30Z

Core concept looks good to me. I'm mostly waiting to check up on some things like instantiation count and testing some surface-level alternatives. Should be done by the end of the week.

mhuggins · 2026-03-10T19:07:48Z

@LeCarbonator Just wanted to follow up to see if there's anything else needed here. I can rebase my branch, just let me know!

crutchcorn

This is awesome. Sorry for missing it on my end. Got @LeCarbonator's approval privately as well. Thank you for this!

# Conflicts: # packages/form-core/src/FieldApi.ts

coderabbitai · 2026-05-10T19:34:26Z

Caution

Review failed

Pull request was closed or merged during review

📝 Walkthrough

Walkthrough

This PR enforces a type-level constraint preventing synchronous validators in TanStack Form from returning Promises. A new RejectPromiseValidator conditional type is introduced and applied to all sync validator callbacks in both FieldApi and FormApi, with type-level tests confirming the constraint works as expected.

Changes

Sync Validator Promise Rejection

Layer / File(s)	Summary
Type Utility Foundation `packages/form-core/src/util-types.ts`	New `RejectPromiseValidator<T>` conditional type detects Promise/PromiseLike return types and resolves them to `never`, preventing Promise-returning validators while preserving `any` types for mocks.
FieldApi Validator Types `packages/form-core/src/FieldApi.ts`	All synchronous validator options (`onMount`, `onChange`, `onBlur`, `onSubmit`, `onDynamic`) wrapped with `RejectPromiseValidator`; import statement updated to include the new type utility.
FormApi Validator Types `packages/form-core/src/FormApi.ts`	All synchronous validator properties (`onMount`, `onChange`, `onBlur`, `onSubmit`, `onDynamic`) wrapped with `RejectPromiseValidator`; import statement updated to include the new type utility.
Type-Level Tests `packages/form-core/tests/FieldApi.test-d.ts`, `packages/form-core/tests/FormApi.test-d.ts`	Type tests verify that Promise-returning synchronous validators are rejected with `@ts-expect-error` assertions on `FieldApi` and `FormApi` instances.
Release Documentation `.changeset/silver-mails-play.md`	Changeset entry documents patch version release noting synchronous validators will no longer permit Promise returns.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Poem

🐰 A promise to reject all promiselike things,
sync validators shed their async wings,
TypeScript ensures the contract is tight,
no sneaky returns in the dead of night! ✨

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately and specifically describes the main change—adding type constraints to prevent synchronous validators from returning Promises across both FormApi and FieldApi.
Description check	✅ Passed	The description clearly explains the motivation, implementation approach, and follows the template with all required sections completed and checkboxes marked appropriately.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

Create PR with unit tests

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

mhuggins · 2026-05-11T13:08:22Z

Awesome, thanks for getting this merged!

mhuggins force-pushed the prevent-synchronous-promises branch from 5924423 to 2198362 Compare January 9, 2026 15:57

fixup! ci: Version Packages (TanStack#1977)

6b927d2

LeCarbonator reviewed Jan 10, 2026

View reviewed changes

Comment thread packages/form-core/src/util-types.ts

crutchcorn approved these changes May 10, 2026

View reviewed changes

Merge branch 'main' into prevent-synchronous-promises

ec84898

# Conflicts: # packages/form-core/src/FieldApi.ts

crutchcorn merged commit 01f51b5 into TanStack:main May 10, 2026
8 of 9 checks passed

github-actions Bot mentioned this pull request May 10, 2026

ci: Version Packages #2168

Merged

Uh oh!

Conversation

mhuggins commented Jan 9, 2026 • edited by coderabbitai Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🎯 Changes

✅ Checklist

🚀 Release Impact

Summary by CodeRabbit

Uh oh!

changeset-bot Bot commented Jan 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

nx-cloud Bot commented Jan 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

pkg-pr-new Bot commented Jan 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

mhuggins commented Jan 10, 2026

Uh oh!

Uh oh!

codecov Bot commented Jan 10, 2026 • edited by sentry Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

mhuggins commented Jan 15, 2026

Uh oh!

LeCarbonator commented Jan 16, 2026

Uh oh!

mhuggins commented Mar 10, 2026

Uh oh!

crutchcorn left a comment

Choose a reason for hiding this comment

Uh oh!

coderabbitai Bot commented May 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Review failed

Walkthrough

Changes

Estimated code review effort

Poem

Uh oh!

Uh oh!

mhuggins commented May 11, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

mhuggins commented Jan 9, 2026 •

edited by coderabbitai Bot

Loading

changeset-bot Bot commented Jan 9, 2026 •

edited

Loading

nx-cloud Bot commented Jan 10, 2026 •

edited

Loading

pkg-pr-new Bot commented Jan 10, 2026 •

edited

Loading

codecov Bot commented Jan 10, 2026 •

edited by sentry Bot

Loading

coderabbitai Bot commented May 10, 2026 •

edited

Loading